fix(resume-checker): show grading outages to users and stop false /api/grade errors - #37

Summary

Four /api/grade issues from Dash0 (Oct 8–9), fixed in the route and the resume-checker page.

 /api/grade
   parseResume(pdf)
-    render every page's text            # loads fonts → "TT: undefined function" WARNs
+    read metadata only                   # grading only uses info.Author
-    pdf.js error ∉ {InvalidPDFException, Invalid PDF structure} → 500 GradingError
+    any pdf.js error → 400 InvalidPDFException
   generateObject(gemini-2.5-flash)
+    maxOutputTokens 8192, thinkingBudget 4096   # runaway generation fails fast, not at 60s
+    log { finishReason, usage } on success and on NoObjectGeneratedError
   catch
-    gateway ≥500 → 503
+    gateway 402 (budget) | 429 | ≥500 → 503 GradingUnavailable

 <ResumeChecker> (src/resume-checker/pages/index.tsx)
-  {error && <ErrorBadge error={error || mutationError} />}   # hid every API error since 0e9da65 (Jan 16)
+  <ErrorBadge error={error || mutationError} />

GradingUnavailable copy: "Perdón, no podemos analizar tu CV en este momento. Probá de nuevo en unos minutos."

Evidence

• Budget outage (Oct 8, 16:36–16:42 UTC): GatewayInternalServerError: Team budget exceeded (402)
  Before: 500 GradingError. Users were sent back to the upload page with no message.
  After: 503 GradingUnavailable. With a mocked 503 in Chrome, the badge shows the new copy, and a fresh page load shows no badge.
• Unreadable PDF (Oct 9, 22:33 UTC, ×3): UnknownErrorException: Command token too long: 128
  The caller is candidate-portal's hourly GradeAshbyResumesJob (infra/functions/gradeAshbyResumes.ts), which grades real candidate resumes from Ashby. The ×3 is its retry loop (MAX_GRADING_RETRIES = 3).
  Before: 500 + alert. The cron stored no grade, so the same candidate was retried every hour.
  After: 400 InvalidPDFException. The cron's InvalidPDFException branch stores its placeholder C grade ("invalid PDF") and stops retrying. That error string is part of the cron's contract, so don't rename it.
  Checked locally: a handmade PDF that throws the same error in pdf-parse, POSTed to a local dev server, returns 400 {"error":"InvalidPDFException"}.
• Timeouts (Oct 7 ×1, Oct 9 ×3 from one IP): calls ran the full 60s while normal grades take 9–27s.
  After: output and thinking are capped. Not reproducible locally; the new usage logs will confirm the cause.
• Tests: bun tsc clean, vitest 79/79. New cases:

  gateway 402 → 503 GradingUnavailable
  gateway 429 → 503 GradingUnavailable
  other gateway 4xx → 500 GradingError
  generateObject gets maxOutputTokens 8192 + thinkingBudget 4096
  NoObjectGeneratedError → 500, logs finishReason
  pdf.js UnknownErrorException → 400 InvalidPDFException
  parseResume renders no page text
  

Merge Danger

Door: two-way

Revert to roll back. Nothing is persisted.

Blast Radius: grading

The token caps were set without measuring production usage. If normal grades need more than 4096 thinking tokens, grades could get worse or fail with finishReason: "length". Watch the new outcome: "graded" usage logs after deploy and raise the caps if they run close. Consumers: the resume-checker page and candidate-portal's GradeAshbyResumesJob. That cron also gets the new 503 GradingUnavailable during gateway outages. It treats it like the old 500 (3 retries, then again next hour). A cap-induced 500 would leave its candidates ungraded the same way. The error badge now also shows API errors, so users may see a past error for up to 5 minutes when they return to the page.

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}